JCSM Shareware Collection 1993 November

home *** CD-ROM | disk | FTP | other *** search

/ JCSM Shareware Collection 1993 November / JCSM Shareware Collection - 1993-11.iso / cl720 / comgrapj.lzh / CGREF.DOC < prev next >

Wrap

Text File | 1993-06-12 | 141KB | 3,159 lines

CommonGraphics TM Programmer's Guide Version 2.2 Rialto Software 4179 Woodland Drive Suite 15B Ann Arbor, MI 48103 (313) 426-5295 Copyright Notice Copyright 1992 by Rialto Software. All rights reserved worldwide. License Agreement This software product and documentation is licensed by Rialto Software to the original purchaser for use under the following terms only: the software may only be used on a single computer at a time; the software may be transferred from one computer to another provided that the software is used on only one computer at a time; copies of the software may be made for backup purposes only. Copying, duplicating, selling or using the software or documentation contrary to the terms in this license agreement is not permitted. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means without the express written permission of Rialto Software 4179 Woodland Drive Suite 15B Ann Arbor MI 48103, (313) 426-5295. Disclaimer THERE ARE NO WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR ANY PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THIS SOFTWARE IS ASSUMED BY THE CUSTOMER, EITHER AS AN INDIVIDUAL OR COMPANY. Some states do not allow the limitation on implied warranties or on how long they last, or the exclusion or limitation of liability or consequential damages, so these limitations and exclusions may not apply. No dealer, company or person is authorized to expand or alter these warranties or this agreement. Any such representation will not bind Rialto Software. Rialto Software reserves the right to revise this publication and to make changes to the software without obligation to notify any person of such revision or change. Trademarks CommonGraphics and the Rialto logo are trademarks of Rialto Software. All other brand and product names are trademarks or registered trademarks of their respective companies. The Graphics Model Graphic Image Prsentation CommonGraphics supports two coordinate systems: a World coordinate space over which all primitives are defined, and a Normalized Device Coordinate space which provides a level of independence between the application and the physical device. The application is never concerned about the coordinate system of the actual device. Transformations are performed by CommonGraphics to transfer one coordinate system into another. The application is only responsible for defining the object in World Coordinate Space and the location on the physical device, in Normalized Device Coordinates, where the object is to be displayed. All characteristics of viewing, such as aspect ratio and screen resolution, are handled by CommonGraphics. World Coordinate Space The World Coordinate Space, or simply World Space, is a two-dimensional Cartesian coordinate space of theoretically infinite extent and precision. Locations in World Space are identified by the form (X, Y). At the center of World Space is the origin, or the (0, 0) coordinate. The X-axis and Y-axis run to infinity in the horizontal and vertical directions, respectively. In reality, World Space is limited by the precision of floating point numbers on the target hardware. Values to the right of the origin along the X-axis are represented by positive numbers, to the left by negative numbers. Values above the origin along the Y-axis are represented by positive numbers, below by negative numbers. The application program uses primitive functions, such as DRAW LINE and DRAW CIRCLE, to create objects, or structures as they are formally referred as in CommonGraphics, in World Space. The units applied to the primitives are arbitrary. They can refer to miles or inches or millimeters or whatever is appropriate for the particular object. All objects should be created using the same coordinate units. The application has full control over which objects are displayed using views and windows (see the sections by the same name later in this chapter). Common objects can be defined based on the standard World Space origin and later moved, or transformed, to another location in the assembled object, which is then displayed. Normalized Device Coordinate (NDC) Space The Normalized Device Coordinate Space is a two- dimensional Cartesian coordinate space defined by the unit square bounded by the points (0, 0) and (1, 1). Normalized Device Coordinates are used by the application to refer to an area on the physical graphics device where the objects created in World Space are to be displayed. Using NDC Space, the application does not have to change when moving from device to device that have different physical characteristics. The NDC Space can be thought of as being overlaid on top of the physical graphic screen. Since most graphic screens are not perfectly square, a region of NDC Space will not be available to the application. After the CommonGraphics system is INITIALIZEd, the INQUIRE WORKSTATION function will return the actual size of NDC Space. In Figure 3-2, the invisible portion of NDC Space is represented by the shaded region. The point defined by Aspect Ratio, which is returned from INQUIRE WORKSTATION, represents the maximum Y value that should be used when defining Views. All objects are clipped to the visible portion of NDC Space. Views Objects in World Space are displayed on the screen in an area referred to as a view. Other graphics standards or textbooks may refer to this region as a viewport. Views are used in conjunction with windows to display selected regions of World Space. Primitives are mapped from World Space into a view on the physical graphics device. The OPEN VIEW function allows the application to specify this region of the screen in Normalized Device Coordinates, along with a background color and a border style. A view cannot be defined outside of the NDC range of the physical screen. For example, if the physical screen has a NDC Space range of (0.0, 0.0) to (1.0, 0.75), a view cannot be defined as (0.0, 0.0) to (1.0, 0.80). The application should always make view areas consistent with the NDC limits returned from INQUIRE WORKSTATION. Multiple views may be defined and open at the same time. Refer to figure 3-3 in the following section titled Windows. Views may also be defined whose regions overlap with other views, however, these overlapping regions have restrictions when they are open at the same time. Refer to the discussion on OPEN VIEW in Chapter 5, Functions, for a list of these restrictions. A view may be defined but not visible by using the CLOSE VIEW function. For example, a full screen view may be defined by the region (0.0, 0.0) to (1.0, 0.80), and 2 half-screen views may be defined with regions of (0.0, 0.0) to (0.5, 0.0) and (0.6, 0.0) to (1.0, 0.80). These different views can be used or OPENed at different points in the application. Since the NDC location for a view is specified each time the view is opened, the location of the view can be moved, enlarged or reduced each time the view is opened. Objects are displayed in a view through the post and unpost functions. Each of these functions is discussed in more detail under Graphic Primitive Organization in this chapter. Windows Each view has an associated window that is a sub- region of the World Space for that view. The window is a roving rectangle whose size and position is controlled by the application. It is only the content of the window that is actually displayed in a view. The portion of an object that lies outside of the window is temporarily removed or clipped when the object is displayed in the associated view. The SET WINDOW function specifies the window by a length and height, with the initial center of the window being the origin or (0, 0) coordinate in World Space. The PAN function allows the window to be moved anywhere within the World Space by specifying a new center coordinate. The ZOOM function changes the length and height of the window so that either more or less of the object is contained within the view. The next section, titled Coordinate Space Transformation, shows how the size and location of the window determines the size and appearance of the displayed image. Multiple views and windows can be used to display a different image of the same object from World Space. Figure 3-3 shows three views that contain the same image of the bicycle defined in World Space. The only difference between the images in the Views is the size and location of the Window in World Space which are controlled using the SET WINDOW, PAN and ZOOM functions. Consider another example where an application has created four objects in World Space, each in a different quadrant. The objects could be displayed simultaneously by OPENing a single view with a window in World Space large enough to contain all four objects. They could also be displayed by OPENing four views, each with a window defined over a different quadrant. Each view is initialized with a window of length 100 units. The height will vary depending on the size of the view. However, this default window is adjusted to reflect the same aspect ratio as the associated view. Refer to the following section titled Window to View Size Relationship. Coordinate Space Transformation Objects from World Space are displayed in a view through a series of transformations. These are the actions that CommonGraphics takes to transform the image in World Space to the region associated with the view on the physical graphics device. There are actually two transformations: mapping the window in World Space to the view and mapping the view to the physical graphics device. Both of these transformations are carried out by CommonGraphics and are totally transparent to the application. The center of the window in World Space is transformed to the center of the view. Window to view size relationship When any view control function is applied to the window of a view, the resultant window may not match the relative proportion of the view. The relationship between the height and width of such a rectangular region is referred to as the aspect ratio. A rectangle whose vertical height is 75 units and whose horizontal length is 100 units has an aspect ratio of 0.75. Windows are always maintained with the same aspect ratio as the view to which they are applied. The aspect ratio of a view does not have to match the aspect ratio of the physical graphics device, but remember, CommonGraphics will not allow a view to be OPENed that is defined outside of the NDC Space for the particular device. If the size of a window needs to be adjusted, CommonGraphics always adjusts the window such that more viewing range is provided than was originally requested, never less. If SET WINDOW is used to define a window with a length of 10 units and a height of 7 units for a view whose aspect ratio is 0.5, CommonGraphics will automatically adjust the length of the window to 14 units to match the aspect ratio of the view. If the same window is defined, but with a height of 4 units, the height is adjusted to 8 units to match the aspect ratio of the view. Both examples show that more of object is always displayed. Without this automatic adjustment, objects would be incorrectly scaled as they were transformed to the view. After each view control function, the INQUIRE VIEW TRANSFORMATION function can be used to find the exact window boundaries. Primitives Primitives are the basic entities upon which more complex objects are constructed. Primitives are defined using the geometric functions provided by CommonGraphics. Objects are created as either a single primitive or by assembling a series of primitives in World Space. The actual appearance of the primitive is determined by: the associated primitive attributes, described in the following section, titled Primitive Attributes, and the size of the window and view in which the primitive is drawn. CommonGraphics supports the following primitive functions: DRAW ARC, DRAW ARROW, DRAW BSPLINE, DRAW CIRCLE, DRAW ELLIPSE, DRAW MARKER, DRAW LINE, DRAW POLYLINE, DRAW RECTANGLE and DRAW TEXT. Arguments to these functions include World Space coordinates and values. A circle, for example, is assembled in World Space by a center point and a radius. Primitive attributes Each primitive has an associated set of image characteristics that define how the primitive is to appear on the screen. These include color, style, line thickness and a number to identify each primitive or series of primitives. A circle, for example, can be drawn as a RED, DASHED line. The same circle could have been drawn using a SOLID line. These characteristics are the attributes of the primitive. CommonGraphics supports the following primitive attribute functions: SET LINE COLOR, SET LINE STYLE, SET LINE WIDTH, SET INTERIOR STYLE, SET TEXT COLOR and SET ELEMENT IDENTIFIER. Attributes are defined globally over all views, windows and objects. As calls are made to the attribute functions, SET LINE COLOR or SET LINE STYLE, for example, CommonGraphics remembers this new value and applies it to each new primitive. Changes to attributes do not effect the appearance of any primitive that previously existed. Not all of these attributes apply to each of the primitives. Circles have color, use a particular line style to represent the circumference, and can be filled with a specified interior style. Lines do not have an interior and, therefore, cannot be filled. CommonGraphics uses only those attributes that apply to the primitive. Refer to the appropriate section in Chapter 5, Functions, for a further discussion of the individual primitive and the attributes used by each. The range of attributes varies widely across different graphic devices. For example, intelligent graphic devices typically support hardware generated line styles, interior fill styles, etc., while less intelligent devices only support line drawing. The attributes supplied with CommonGraphics define the minimum set of attributes that are supported. If a graphic device does not support this minimum set, the attribute is simulated by CommonGraphics. For example, if one of the minimum line styles is not supported by the physical device, the style is drawn by CommonGraphics using a series of line segments. This simulation will not use one primitive to simulate another. Line styles will not be used to simulate missing colors, for example. Graphic Primitive Organization Many applications need the ability to take basic primitives and construct high-level objects. These objects can then be referenced as a unit, rather than as a series of individual primitives. The image of the bicycle shown in Figure 3-3, for example, consists of two wheels, a seat, a frame and handlebars. Each of these can be created and referenced as a unit. The seat, for example, can be referenced as a unit and placed at a specified location in World Space. The ability to define high-level objects for each of these components allows an application to select, edit or change them as a single unit. The application can experiment with the bicycle design using different images for the seat or wheels with a single CommonGraphics function. Graphic data is organized into units called structures, which can be related to each other hierarchically. At the lowest level in the hierarchy, primitives and attributes are used to compose objects which may, in turn, be referenced as part of objects at the next highest level, and so on. The hierarchy resembles a tree structure with the root structure at the top and children branching off from the root. Structures contain a collection of primitives and associated attributes. These are referred to as structure elements. Structure elements cannot exist outside of structures. Each structure has a one-to- one correspondence to a unique structure identifier which is provided by the application program. Only one structure may be open at one time. The time at which structures are displayed is independent of when primitives are placed into the structure. The application may, at any time, identify a particular structure for display in a view, either before, during or after the primitives have been added to the structure. This is referred to as posting. A structure is posted to a view to display and unposted to erase. Posting is discussed further in the following section titled Structure Display. When a structure is posted in a view, all primitives currently associated with the structure are displayed in the view. Figure 3-4 shows a typical example of a structure hierarchy being posted to multiple views. Notice that the same structure can be both posted directly to a view and referenced by other structures, and that a The images of these multiple references can vary depending on the location, rotation and translation values supplied to the REFERENCE STRUCTURE function. Any subsequent changes to the structure, either through primitives being added, edited or deleted, will immediately be reflected in the view until the structure is identified for removal, or unposted, from the view. Removal of a structure from a view does not affect the existence or content of the structure or data storage. Attributes are associated with a primitive when the primitive is added to a structure. If a primitive is removed from a structure, the attributes associated with the remaining primitives are not affected. There are two types of structures: retained and non-retained. Retained structures When an application opens a retained structure with the OPEN STRUCTURE function, all subsequent primitives and associated attributes are placed into graphics data storage. View control, edit, inquiry or input functions can be used by the application program to act on or examine the contents of retained structures. Non-retained structures When an application opens a non-retained structure with the OPEN NON RETAINED STRUCTURE function, all subsequent primitives are lost. Primitives added to a non-retained structure are displayed at the time they are added. If the non-retained structure is not posted to a view prior to the primitive being added, the primitive is ignored. Primitives of a non-retained structure continue to be displayed until the next regeneration of the view occurs through any view control or visibility function. Classes Each structure is further divided into a pre- defined number of classes. Classes are automatically maintained by CommonGraphics. The organization for structures and classes can be described best as a two-dimensional table, much like a spreadsheet. Each column in the table represents a structure created by the application. Each row represents one of the pre-defined classes of GEOMETRY, NOTE or REFERENCE. As each primitive is added to a structure, it is placed in a class within the currently open structure, based on the type of the primitive. Line, circle and other geometric primitives are added to the GEOMETRY class, text primitives are added to the NOTE class and references to other structures are added to REFERENCE class. Refer to the section that follows, titled Structure Hierarchy, for a discussion on structure references. During structure traversal for either view control, editing or picking, CommonGraphics will only examine those classes that apply and in the order of GEOMETRY, then NOTE and then REFERENCE. When a structure is traversed for primitive selection, only those classes that contain an allowed response primitive are examined. The NOTE class, for example, will only be examined for primitive selection if TEXT is a valid response. Classes optimize performance and, as shown in the following section on Visibility, allow the application or user to selectively decide how much and what type of primitive is displayed at any given time. Visibility of data The visibility of both structures and classes can be manipulated with the SET STRUCTURE VISIBILITY and SET CLASS VISIBILITY functions. The contents of a structure are visible only if the structure is posted to a view, the primitive is within the window of World Space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. The default visibility for both the structure and the class is ON. Consider the two-dimensional table in Figure 3-5. In order for each individual box to be visible, both the structure and class that intersect at this box must be ON. Sturcture hierarchy Structures can relate to other structures in a hierarchical network. A special type of primitive exists called a structure reference which, when added to an open structure using the REFERENCE STRUCTURE function, causes the primitives in the referenced structure to appear as if they were created in the open structure. When a structure is referenced, using the REFERENCE STRUCTURE function, the application can identify a transformation to be placed on the primitives in the referenced structure. If the referenced structure contains referenced structures, the transformation becomes cumulative. Suppose structure A references structure B with a scale of 2, that is, the primitives in structure B appear twice as large when drawn with structure A. If structure A is now referenced by structure C with a scale of 3, the primitives in structure B will appear 6 times larger when drawn in structure C. The same logic applies to transformations and rotations. Using the example of the bicycle diagram from Figure 3-3, the root structure might be the frame, and the seat, wheel and handle bar structures could be referenced within the frame structure. A major advantage of using structures in this case is that the primitives for the wheel structure are stored once, but referenced several times. Refer back to Figure 3-4 for a representation of hierarchical structures. Structure references cannot be nested, however, CommonGraphics does not explicitly check for this condition. Referring to Figure 3-6, structure A may not reference structure B if structure B references either structure A or another structure that directly or indirectly references structure A. Strucuture operations Structures may be operated on in one of three ways: through general editing operations, operations performed on the structure as a whole and operations that support the viewing of the primitives within the structure. Structure editing Structures may be edited by inserting new primitives, and by changing or deleting existing primitives. Inserting primitives into a new structure and appending primitives into an existing structure are accomplished in the same way. The OPEN STRUCTURE or OPEN NON RETAINED STRUCTURE functions are used to open a structure for editing. If another structure is currently open, it will automatically be closed before the new structure is opened. The CLOSE STRUCTURE function can be used to close the currently open structure explicitly. If the currently open structure is not known, the INQUIRE OPEN STRUCTURE function can be used to find the information. When a structure is open, the application program may simply insert new primitives through the basic primitive calls such as DRAW ARC or DRAW LINE. All primitives are inserted at the end of the structure. The application program is responsible for associating each primitive with an identification number through the SET ELEMENT IDENTIFIER function. This number can be used later on to refer to the exact primitive for either editing or retrieval purposes. If an identifier is not assigned by the application, a default value of zero is used. An element identifier is returned with each valid pick to let the application know which primitive was selected. Identifiers do not have to be unique, either within a single structure or over several structures. Several primitives within the same structure can have the same identifier so that they may later be manipulated as a group. An application program could create a new primitive, for example a drafting dimension type, by using a series of calls to DRAW ARROW, DRAW LINE and DRAW TEXT and associating them by using the same element identifier. Later in the application, this new primitive type could be examined as a unit because of the similar element identifier. A structure may also be edited by removing primitives within the structure. The DELETE ELEMENT and DELETE ELEMENT RANGE functions rely on element identifiers to locate and remove specified primitives. Since attributes are associated directly with a primitive, deleting a primitive has no effect on the attributes of other primitives in the structure. Structure maintenance There are several functions that apply to a structure as a whole. All of the primitives of a structure may be deleted through the EMPTY STRUCTURE function. This function only deletes the contents of the structure and has no effect on the existence, references to, or view posting of the structure. A structure and all associated primitives may be deleted from graphic storage through the DELETE STRUCTURE function. This function has no effect on structure references. If a reference to a non- existent structure is encountered, the reference is ignored. Structure references can only be deleted through the DELETE ELEMENT or DELETE ELEMENT RANGE functions. The DELETE ALL STRUCTURES function is provided to delete all structures. Structures that are deleted and also posted to a view, are unposted from the view before being deleted. A structure identifier may be changed through the CHANGE STRUCTURE IDENTIFIER function. The new identifier must be unique. This function does not effect structure references. To change a structure reference, the CHANGE STRUCTURE REFERENCE function should be used. Inquiry functions return information about structure identifiers to the application program. INQUIRE OPEN STRUCTURE returns the identifier of the currently open structure, INQUIRE STRUCTURE EXISTS returns whether or not a structure exists, INQUIRE STRUCTURES returns each existing structure identifier, and INQUIRE STRUCTURES POSTED TO VIEW returns each structure that is displayed in a specified view. Structure display Primitives within a structure are only displayed after the structure has been posted to a view through the POST STRUCTURE TO VIEW, POST ALL TO VIEW, or POST TO ALL VIEWS functions. Posting should only be done on root structures and not on structures that are only used as references in other structures. A root structure is one that is at the top of the structure hierarchy. A structure may be displayed because it is both explicitly posted and referenced by another structure. Display priority is assigned based on the order the structures are posted to a view, with the first posted structure being displayed before latter posted structures. Primitives are similarly removed from the display by unposting the associated structure through the UNPOST ALL FROM VIEW, UNPOST FROM ALL VIEWS and the UNPOST STRUCTURE FROM VIEW functions. Primitives may also be removed from the display by making the associated structure or class invisible through the SET STRUCTURE VISIBILITY or SET CLASS VISIBILITY functions, respectively. If a primitive is deleted from a structure, it is also removed from the display. Refer to the section titled Structure Editing above. Request for input Graphic input refers to information returned to the application program as a direct result of some action taken on the part of the user using a graphic input device such as a mouse or the keyboard. Moving the graphic cursor within tolerance of a primitive and pressing a button or key to indicate selection causes PICK information to be returned to the application indicating the type and location of the primitive. If the graphic cursor is not within tolerance of a primitive, but still inside a view, LOCATE information is returned indicating just the position of the graphic cursor. With the graphic cursor outside of a view, SCREEN information is returned. Text entered from the keyboard returns STRING information. Pick types and classes Graphic standards, including PHIGS, typically separate the functions used for input by class, including event, sample and request, and by type, including pick, choice, locator, valuator and string. While this may appear to provide the most in flexibility, it can be less flexible for applications that require the ability to allow multiple selection types and classes for each request for input. For example, an application may allow a user to select from a menu or simply type in the item name from the keyboard. In other graphic standards or toolkits, this is accomplished by using a series of functions where the application program is, in effect, querying the state of each input class until a valid response is detected. This logic can often be difficult to program. CommonGraphics is designed with a more common approach to requests for input. Rather than providing individual functions for these various types of input types and device classes, a single input function, REQUEST INPUT, handles all requests. The application program is informed of the type and class of input in the returned request buffer. CommonGraphics supports the PICK, LOCATE, SCREEN and STRING device classes. Name sets There are cases when the application program may want to limit the type and class of input that is allowed. For example, in a CAD application, the user may want to define a point as the intersection of two lines. In this case, the application may not want the user to be allowed to select an arc or circle or any other primitive besides a line. Input from any device class except PICK would not be allowed. The application program can limit the type and class of selection through the use of name sets. Name sets allow the user to control which device classes are enabled or primitives are examined during a request for input. There can be any number of name sets defined based, in part, on the number of different input criteria that the application program needs. There is no difference between name sets that contain device classes and those that contain primitive values, i.e. the application does not identify the type of set in any function that deals with name sets. The application is responsible for using the appropriate name set in the correct context. Name sets are created and managed by the functions ADD NAME TO SET, ADD ALL NAMES TO SET and REMOVE NAME FROM SET. Structure pickability If addition to pick filters, the application can control which structures are examined for a valid selection through the SET STRUCTURE PICKABILITY function. Structures whose pickability is OFF will not be examined. Pick class notification If a primitive is within tolerance of the graphic cursor, and the button or key is pressed to confirm selection, the primitive will be highlighted to verify the selection to the user. Highlighting takes the form of quickly erasing and redrawing the selected primitive using the associated attributes. Primitives whose interiors are filled are highlighted by also erasing and redrawing the interior. A special case is made for TEXT and STRUCTURE REFERENCE primitives. Only the individual character and individual primitive is highlighted if either of these two primitives are selected. There may be times when the content of a structure should not be highlighted, or perhaps the application wishes to use a different method to highlight. Menus are a case in point. The verification to the user may be that a sub-menu is displayed, or the graphic image changes as a result of a menu selection. The SET STRUCTURE HIGHLIGHT function can be used to control whether the primitives of a structure are highlighted when selected. Structures whose highlight is OFF will not be highlighted. String class notification Each character is echoed on the graphics device as it is entered from the keyboard. The SET STRING RESPONSE function is used to set the location and color for the characters of the string. Since input is not entered in relation to a view, the location for the echo is specified in NDC space. The location has several important design considerations for the application. As the user erases characters with the backspace key, they are removed from the screen using the background color specified in SET STRING RESPONSE. If the echo location crosses several views which have backgrounds of different colors, the characters will not appear to erase even though they will not be contained in the response. The STRING response area should be designed to be in a separate area of the screen, completely contained in a single view, or used across several views that share a common background color. Errors There are three types of errors possible in CommonGraphics: recoverable, non-recoverable and internal. Recoverable errors Many functions return a status to the application program that indicates whether or not the function completed successfully. Several of the INQUIRY functions, for example, provide for the application program to loop through the contents of graphic storage and return information about all structures or views. When the end of the list is encountered, a status is returned that tells the application program to stop the inquiry. For this type of error, failure to stop has no effect on the application program other that it will receive more of these error statuses. This type of status is always TRUE, if the function completed successfully, or FALSE if the function did not complete successfully. Non-recoverable errors Errors are issued as a result of the application program using a function incorrectly. Errors generally have the effect that the application program does not behave in the expected manner. The application program may have used a primitive function, such as DRAW LINE, without first opening a structure. CommonGraphics will ignore the primitive function and the application developer or user will not see the result. Other examples of errors include opening a view with an NDC space outside the range of the physical screen, posting a structure to a view where either the structure or view does not exist, and attempting to draw primitives with invalid data such as circles with a zero radius. Errors that are visual in nature can be corrected using the DUMP function which produces a readable form of graphics storage. The user can find out which structures are posted to which views, as well as detailed information about each primitive. Errors may also occur that are not as visual. Closing a structure that is not open or attempting to add a non-existent device class or primitive to a name set are errors that the user or developer will not visually notice. Internal Errors Internal errors are a result of CommonGraphics being unable to allocate system memory to place information in graphics storage. Error Logging All non-recoverable and internal errors are written to an error file that can be examined after CommonGraphics has terminated. The error messages have been designed to be as informative as possible. Most error messages include the name of the function that is in error and, where appropriate, the name of the structure or view that caused the error. Refer to Appendix C for a list of all error messages. Functions This chapter contains detailed information about each CommonGraphics function. Each function is listed alphabetically. Information includes a description of the function, the formal language syntax, a list of related functions and a return value. For additional information, refer to Appendix A which provides details about each data type used by the functions, Appendix B which lists each function by class, and Appendix C which lists any associated error messages. ADD ALL NAMES TO SET Add every primitive or device class to the specified name set. void cg_add_all_names_to_set (name_set) t_name_set *name_set Name of the set Name sets allow the user to control which device classes are enabled or primitives are examined during a request for input. This function should be used in cases where all device classes are to be enabled or primitives are allowed to be selected. This function can also be used to narrow the allowed values in a set that contains most of the device classes or primitives, except for a few. In this case, this function can be used in conjunction with the REMOVE NAME FROM SET function to selectively remove a few of the classes or primitives. This may be preferable over having to enumerate each device class or primitive in sequence. Since name sets contain both devices classes and primitives, care should be taken to ensure proper use. ADD NAME TO SET Add a single device class or primitive to the specified name set. void cg_add_name_to_set (name_set, value); t_name_set *name_set Name of the set int value Device class or primitive to add Name sets allow the user to control which device classes are enabled or primitives are examined during a request for input. This function adds a single device class or primitive to a specified name set. If a name set is to contain more than one class or primitive, this function can be called repeatedly to enumerate each class or primitive in the set. Since name sets contain both devices classes and primitives, care should be taken to ensure proper use. CHANGE REFERENCE ABS Change the transformation that is associated with a referenced structure. The new origin for the structure is in relation to the absolute origin (0, 0) of World Space. void cg_change_reference_abs (structure_name, reference_name, element_id, translate, angle, scale) char structure_name[] Name of the structure to search for references char reference_name[] Name of the referenced structure to change long element id Identifier of the referenced structure t_world_coord translation New center of the referenced structure real angle Degrees of rotation real scale Scale factor If the value for the element identifier of the referenced structure to change is specified as -1, all referenced structures with the matching name, regardless of the element identifier, will be changed. CHANGE REFERENCE NAME Replace a structure that is being referenced in a structure with another structure. void cg_change_reference_name (structure_name, element_id, old_structure_name, new_structure_name) char structure_name Name of the structure to search for referenced structures to change long element_id Identifier of the referenced structure to change char old_structure_name[] Name of the existing referenced structure char new_structure_name[] New name for the structure If the name of the structure to search for the referenced structure(s) is blank, all structures will be searched. If the value for the element identifier of the referenced structure to change is specified as -1, all referenced structures with the matching name, regardless of the element identifier, will be changed. CHANGE REFERENCE REL Change the transformation that is associated with a referenced structure. The new origin for the structure is in relation to the origin (0, 0) of the structure that is being changed. void cg_change_reference_rel (structure_name, reference_name, element_id, translate, angle, scale) char structure_name[] Name of the structure to search for references char reference_name[] Name of the referenced structure to change long element id Identifier of the referenced structure t_world_coord translation New center of the referenced structure real angle Degrees of rotation real scale Scale factor If the value for the element identifier of the referenced structure to change is specified as -1, all referenced structures with the matching name, regardless of the element identifier, will be changed. CHANGE STRUCTURE NAME Change the name of an existing structure. void cg_change_structure_name (old_structure_name, new_structure_name) char old_structure_name[] Name of the structure to change char new_structure_name[] New name for the structure All structure references that refer to the structure will also be changed to the new structure. If the name of structure A is changed to B, all structure references that refer to structure A will be changed to refer to structure B. To change just the name of a structure reference, use CHANGE REFERENCE NAME. CLOSE STRUCTURE Close the currently open structure. void cg_close_structure (structure_name) char structure_name[] Name of the structure to close New primitives are not allowed until a new structure is opened or an existing structure is re-opened. The name of the structure is included in the calling sequence to help ensure that the proper structure is closed. An error will result if the structure closed is not the same as the currently open structure. Closing a structure has no effect on the content of the structure or on the actual image that is currently visible. CLOSE VIEW Close the currently open view and erase the image from the graphic screen. void cg_close_view (view_name) char view_name[] Name of the view to open All structures that are currently posted to the view remain posted. Structures can be posted to a view that is closed, but the primitives will not be displayed until the view is opened, the structure is posted to another view that is open, or the structure is referenced by another structure whose contents are displayed. DELETE ALL STRUCTURES Remove all structures and primitives from graphics storage. void cg_delete_all_structures (void) All views that are currently visible are cleared. All structures are automatically unposted from all views. DELETE ALL VIEWS Remove all views from graphics storage and erase the image from the graphics screen. void cg_delete_all_views (void) All structures that are posted to the views are automatically unposted. DELETE ELEMENT Remove each element with a specified identifier from a single structure. void cg_delete_element (structure_name, element_identifier) char structure_name[] Name of the structure to search for identifier long element_identifier Identifier of the element(s) to delete If each element is currently visible in any view, it is erased from the view. If an element is not found whose identifier matches the one specified, no action is taken and the calling program is not notified. Removing an element has no effect on the current setting for any attribute, nor does it have any effect on the appearance of subsequent primitives in the structure from which it is removed. DELETE ELEMENT RANGE Remove each element whose identifier is between a specified range from a single structure. void cg_delete_element_range (structure_name, begin_identifier, end_identifier) char structure_name[] Name of the structure to search for identifier long begin_identifier Beginning identifier of the elements to delete long end_identifier Ending identifier of the elements to delete If each element in the range is currently visible in any view, it is erased from the view. If an element is not found whose identifier matches the one specified, no action is taken and the calling program is not notified. The specified range is inclusive. The beginning element identifier must be less than or equal to the ending element identifier in the range. Removing an element has no effect on the current setting for any attribute, nor does it have any effect on the appearance of subsequent primitives in the structure from which it is removed. DELETE STRUCTURE Remove a structure from graphics storage. void cg_delete_structure (structure_name) char structure_name[] Name of the structure to delete The structure is automatically unposted from all views. The contents of the structure, if visible, are erased from the screen. If the structure is the currently open structure, no primitives may be added until a new structure is opened or an existing structure is re-opened. If the structure is referenced by another structure, the reference remains but is ignored at the time that the structure is traversed. The reference can be changed by either renaming it to another structure or by deleting the reference. DELETE ALL STRUCTURES Remove all structures from graphics storage. void cg_delete_all_structures () Each structure is automatically unposted from all views. The contents of each structure, if visible, are erased from the screen. No primitives may be added until a new structure is opened. All structure references are removed. DELETE VIEW Remove a view from graphics storage. void cg_delete_view (view_name) char view_name[] Name of the view to delete All structures that are posted to the view are automatically unposted. The portion of the graphics screen that contains the view is erased. DRAW ARC Draw a circular arc using current attributes for line color, style and width. The attribute for interior style is ignored for circular arcs even if the arc represents a circle. void cg_draw_arc (center, radius, start_angle, end_angle) t_world_coord center Center point for the arc real radius Radius for the arc real start_angle Starting angle for the arc in degrees real end_angle Ending angle for the arc in degrees A circular arc is defined by a center point, a radius and starting and ending angles. All angles assume that 0 degrees is at 3 o'clock with values increasing in the counterclockwise direction. Angles can be expressed as either positive or negative values, however, angles outside of the range 0 to 360 are normalized to that range when drawn. The end angle does not have to be larger than the start angle. If, for example, the arc is defined with a start angle of 0 and an end angle of -45, the arc is drawn counterclockwise from the 325 angle to the 0 angle. A structure must be open before an arc is drawn. DRAW ARROW Draw an arrowhead using current attributes for line color, style, width and interior fill style. void cg_draw_arrow (start_point, length, height, angle) t_world_coord start_point Tip point for the arrow real length Length of the arrow real height Height of the arrow real angle Angle of rotation for the arrow in degrees An arrowhead is defined by a point representing the tip, a length along the base, a height and an angle of rotation. All angles assume that 0 degrees is at 3 o'clock with values increasing in the counterclockwise direction. Angles can be expressed as either positive or negative values, however, angles outside of the range 0 to 360 are normalized to that range when drawn. A structure must be open before an arrowhead is drawn. DRAW BSPLINE Draw a bspline curve using current attributes for line color, style and width. void cg_draw_bspline (number_of_points, point_array) int number_of_points Number of points in the array t_world_coord point_array[] Array containing curve points A bspline curve is defined by a series of control points to produce a smooth curve. An arbitrary number of control points can be specified. The influence that any particular point has on the overall curve can be controlled by, for example, specifying the same control point twice in series. A structure must be open before a bspline curve is drawn. DRAW CIRCLE Draw a circle using current attributes for line color, style, width and interior style. void cg_draw_circle (center, radius) t_world_coord center Center point for the circle real radius Radius of the circle A circle is defined by a center point and a radius. A structure must be open before a circle is drawn. DRAW ELLIPSE Draw an ellipse using current attributes for line color, style, width and interior style. void cg_draw_ellipse (center, x_radius, y_radius, angle) t_world_coord center Center point for the ellipse real x_radius Half the length of the ellipse real y_radius Half the width (height) of the ellipse real angle Angle of rotation of the ellipse An ellipse is defined by a center point, a radius specified along the x and y axis, and an angle of rotation. All angles assume that 0 degrees is at 3 o'clock with values increasing in the counterclockwise direction. Angles can be expressed as either positive or negative values, however, angles outside of the range 0 to 360 are normalized to that range when drawn. A structure must be open before an ellipse is drawn. DRAW LINE Draw a line using current attributes for line color, style and width. void cg_draw_line (start_point, end_point) t_world_coord start_point Starting point for the line t_world_coord end_point Ending point for the line A line is defined by a starting point and an ending point. A structure must be open before a line is drawn. DRAW MARKER Draw a marker using current attribute for line color. void cg_draw_marker (marker_style, point) t_marker_style marker_style Style to draw at the marker point t_world_coord point Point at which to draw the marker A marker is defined by a point and a marker style. Markers maintain a constant size regardless of the view or window currently in effect. A structure must be open before a marker is drawn. DRAW POLYLINE Draw a series of connected lines using current attributes for line color, style, width and interior style. void cg_draw_polyline (marker_style, connect, number_of_points, point_array) t_marker_style marker_style Style to draw at each point, if any bool connect Connect first and last points? int number_of_points Number of points for the polyline t_world_coord point_array[] Array of points for the polyline Each line in the series is defined by a starting point and an ending point. For example, lines are drawn from indices n to n+1, n+1 to n+2, etc. At least two points must be specified. If connect is TRUE, a line will be drawn from the last point to the first point, creating a polygon. Only connected POLYLINEs can have filled interiors. An optional marker symbol can be drawn at each point. A structure must be open before a polyline is drawn. DRAW RECTANGLE Draw a rectangle using current attributes for line color, style, width and interior style. void cg_draw_rectangle (center, length, height, corner_radius, angle) t_world_coord center Center point for the rectangle real length Length of the rectangle real height Height of the rectangle real corner_radius Radius at each corner in degrees real angle Angle of rotation for the rectangle in degrees A rectangle if defined by a center point, a length, a height, a corner radius and an angle of rotation. All angles assume that 0 degrees is at 3 o'clock with values increasing in the counterclockwise direction. Angles can be expressed as either positive or negative values, however, angles outside of the range 0 to 360 are normalized to that range when drawn. A structure must be open before a rectangle is drawn. DRAW TEXT Draw a series of characters using the current attribute for text color. void cg_draw_text (style, lower_left, characters, height, width, angle) t_text_style style Either STRING_TEXT or STROKE_TEXT t_world_coord lower_left Lower left point at which to draw text char characters[80] Text characters to draw real height Character height in World coordinates real width Character width (zero uses 75 % of height) real angle Rotation angle for text A text string is defined by a precision style, a lower left corner to begin the text string, a character height, a character width, the characters to be drawn and an angle of rotation. All angles assume that 0 degrees is at 3 o'clock with values increasing in the counterclockwise direction. Angles can be expressed as either positive or negative values, however, angles outside of the range 0 to 360 are normalized to that range when drawn. STRING precision draws the characters using a hardware available font. The values for character height, width and angle are ignored. Characters can only be drawn horizontally. STROKE precision draws the characters using a software generated font. A structure must be open before a text string is drawn. DUMP Output the content of graphic storage to an ASCII file in a readable form, showing many of the hierarchical relationships. void cg_dump (void) EMPTY STRUCTURE Remove all primitives from a specified structure and erase each primitive from all posted views. void cg_empty_structure (structure_name) char structure_name[] Name of the structure to empty The structure remains posted to views and referenced by structures. If the structure is the currently open structure, the structure remains open. Primitives added after this function continue to be placed in the currently open structure. INITIALIZE Initialize the CommonGraphics system. void cg_initialize (void) This function must be called before any other function. Initial attribute settings are: element identifier 0 interior fill EMPTY line color RED line style SOLID line width 1 text color RED Device specific information is available through the INQUIRE WORKSTATION function. Information includes the type of device, the aspect ratio of the screen which can be used when opening views, and other hardware characteristics. INQUIRE CLASS VISIBILITY Return information about whether a class in a specified view is visible. bool cg_inquire_class_visibility (view name, class, value) char view_name[] Name of the view to inquire t_class class Name of the class to inquire t_toggle *value Returned visibility of the class Classes are unique to each view. Turning the visibility of a class in one view ON or OFF does not affect the visibility of the primitives in any other view. Each structure is divided into a predefined number of classes that contain primitives of a certain type. A good way to imagine this is as a table where the columns represent the structures and the rows represent the classes. Structure visibility affects an entire column and class visibility affects an entire row. In order for each individual box in this table to be visible, both the structure and class that intersect at this box must be ON. This classification of primitives provides for better viewing options. If a view becomes too cluttered, classes of primitives can be turned off much like overlays in a textbook. Return value: TRUE if the view exists and the class is valid. FALSE otherwise. INQUIRE NAME SET Return information about whether a device class or primitive is a member of a specified name set. bool cg_inquire_name_set (name_set, value) t_name_set name_set Name of the set int *value Device class or primitive to check in set Name sets allow the user to control which device classes are enabled or primitives are examined during a request for input. Since name sets contain both devices classes and primitives, care should be taken to ensure proper use. For example, the following example, which mixes devices classes and primitives in a single name set, would produce undesired results: name_set = 0; cg_add_name_to_set (&name_set, LINE); cg_inquire_name_set (&name_set, PICK); Return value: TRUE if the device class or primitive is in the name set. FALSE otherwise. INQUIRE OPEN STRUCTURE Return the name of the currently open structure, if any. bool cg_inquire_open_structure (structure_name) char structure_name[] Return name of current open structure Return value: TRUE if a structure is currently open. FALSE otherwise. INQUIRE PICK LIST Return information about each level of the structure hierarchy that was examined during the last request for input. bool cg_inquire_pick_list (value, pick_element) t_selection value Either FIRST or NEXT struct t_group_elem pick_element Next element in the pick list With each request for input using REQUEST INPUT, a buffer is returned that identifies the highest level structure information for the pick. For example, if a primitive within a referenced structure was selected, the request buffer contains information about the structure reference primitive. If the selected primitive is not part of a structure reference, information about the actual primitive, eg. LINE or CIRCLE, is returned. With repeated calls to this function, the application can examine the path through the structure hierarchy that resulted in the pick. The selection value of FIRST returns the first element in the pick list. Subsequent calls to this functions should use the selection value of NEXT. If the pick type identified in the request buffer is not PICK, this function is ignored. If the element type identified in the request buffer is not STRUCTURE REFERENCE, this function returns the same information as contained in the request buffer. Return value: TRUE if an element is returned. FALSE if incorrect selection type or the end of the list is encountered. INQUIRE PRIMITIVE ATTRIBUTES Return information about the current settings for all primitive attributes. void cg_inquire_primitive_attributes (attributes) struct t_attributes *attributes Current attribute values Attributes returned include element identifier, interior fill style, line color, line style, line width and text color. Return value: None INQUIRE STRING RESPONSE Return information about the current settings used to process a response of type STRING during a request for input. void cg_inquire_string_response (echo_pt, echo_color, background_color) t_ndc_coord echo_pt Location to echo each typed character t_color *echo_color Color for typed characters t_color *background_color Color for erasure of characters During a request for input that allows a response class of STRING, each character that is entered is echoed on the screen at the location and using the color that is returned. Since input does not take place in a particular view, the characters can be echoed at any location in NDC space. Return value: None INQUIRE STRUCTURES Return the name of each structure that is currently available. bool cg_inquire_structure (value, structure_name) t_selection value Either FIRST or NEXT char structure_name[] Return name of next structure The selection value of FIRST returns the first structure. Subsequent calls to this functions should use the selection value of NEXT. Return value: TRUE if the structure exists. FALSE if the selection value is incorrect or if there is no next structure. INQUIRE STRUCTURE EXISTS Return information as to whether or not a specified structure is currently available. bool cg_inquire_structure_exists (structure_name) char structure_name[] Name of the structure to check for existence Return value: TRUE if the structure exists. FALSE otherwise INQUIRE STRUCTURE VISIBILITY Return information about whether a structure is visible. bool cg_inquire_structure_visibility (structure name, visible) char structure_name[] Name of the structure to inquire t_toggle *visible Returned visibility of the structure Return value: TRUE if the structure exists. FALSE otherwise. INQUIRE STRUCTURES POSTED TO VIEW Return the name of each structure that is posted to a specified view. bool cg_inquire_structures_posted_to_view (selection, view, structure) t_selection selection Either FIRST or NEXT char view[] Name of the view to search char structure[] Returned name of the next structure The selection value of FIRST returns the first structure posted to the view. Subsequent calls to this functions should use the selection value of NEXT. Return value: TRUE if a structure is returned. FALSE if the selection value is incorrect or if there is no next structure. INQUIRE VIEWS Return the name of each view that is currently available. bool cg_inquire_views (selection, view_name) t_selection selection Either FIRST or NEXT char view_name[] Returned name of the next view The selection value of FIRST returns the first view. Subsequent calls to this functions should use the selection value of NEXT. Return value: TRUE if a view returned. FALSE if the selection value is incorrect or if there is no next view. INQUIRE VIEW ATTRIBUTES Return information about the settings for the background color and border style attributes of a specified view. bool cg_inquire_view_attributes (view_name, color, border_style) char view_name[] Name of the view to inquire t_color *color Returned background color of the view t_view_border_style *border_style Returned border style of the view Return value: TRUE if the view exists. FALSE otherwise. INQUIRE VIEW EXISTS Return information as to whether or not a specified view is currently available. bool cg_inquire_view_exists (view_name) char view_name[] Name of the view to inquire Return value: TRUE if the view exists. FALSE otherwise. INQUIRE VIEW TRANSFORMATION Return information about the viewport and window boundaries for a specified view. bool cg_view_transformation (view, view_ll, view_ur, wndw_ll, wndw_ur) char view[] Name of the view to inquire t_ndc_coord view_ll Lower left NDC coordinate of view t_ndc_coord view_ur Upper right NDC coordinate of view t_world_coord wndw_ll Lower left World coordinate of window t_world_coord wndw_ur Upper right World coordinate of window When any view control function is applied to a view, the resultant window may not match the relative proportion of the view. Windows are always maintained with the same aspect ratio as the view to which they are applied. Windows are automatically adjusted such that more viewing range is provided than originally requested. After each view control function, this inquiry can be used to determine the exact window boundaries. Return value: TRUE if the view exists. FALSE otherwise. INQUIRE WORKSTATION Return device specific information about the graphics device. void cg_inquire_workstation (device_parameters) struct t_device *device_parameters Returned device specific attributes Return value: None OPEN NON RETAINED STRUCTURE Close the current structure, if any, and open a new structure with the specified name. void cg_open_non_retained_structure (structure_name) char structure_name[] Name of the structure to open Primitives added to the structure are not retained. Any view control function applied to a view where a non-retained structure is posted erases the content of the structure from the view. Edit, inquiry or input functions have no effect on non-retained structures. Retained structures are used in the same way as non- retained structures, except that the primitives are saved. The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. The default visibility for both the structure and the class is ON. OPEN STRUCTURE Close the current structure, if any, and open a new structure with the specified name. void cg_open_structure (structure_name) char structure_name[] Name of the structure to open All new primitives are added to this structure. View control, edit, inquiry or input functions may examine the contents of retained structures. Non-retained structures are used in the same way as retained structures, except that the primitives are not saved. The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class is ON. The default visibility for both the structure and the class is ON. OPEN VIEW Open a view, erase the specified view area of the screen and display all posted structures on the screen. void cg_open_view (view_name, view_ll, view_ur, background_color, border) char view_name[] Name of the view to open t_ndc_coord view_ll Lower left corner of view on screen t_ndc_coord view_ur Upper right corner of view on screen t_color color Background color for the view t_border_style border Either NO_BORDER or BOX_BORDER Enumerated values are defined for the first 16 colors that can be used as the background color for the view. The maximum number of colors supported is device specific. Additional colors may be passed to this function without error. Undetermined results will occur if the color value is not supported. Border styles can be used to distinguish the view area. A BOX_BORDER style encloses the view area with a white or red rectangle depending on whether the background color is white. A NO_BORDER style will not enclose the view area. The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. The default visibility for both the structure and the class is ON. The default window is defined with a width of 100 units and a height that varies depending on the height of the view. Overlapping views are supported under the following conditions: 1. the views are not made visible at the same time. An application may define views that overlap, but each should only be made visible during different phases of the application so there is never a true overlap. 2. the views, if visible at the same time, do not share a common, posted structure in which new primitives are added or re-drawn. Views are not redrawn when the overlapping views are closed. 3. Element picking is not required. Primitives that are hidden by the overlapping view would be pickable. Even with these restrictions, some limited use of overlapping views is available. PAN Move the window of a specified view and draw the corresponding primitives in World Space in the view. void cg_pan (view_name, point) char view_name[] Name of the view to change the window t_world_coord point New center point for the window The center point of the window for the specified view is moved to the specified point. The length and width of the window remain the same. The effect in the view is that a different image will appear POST ALL TO VIEW Add all currently available structures to the list of structures to be displayed in a specified view. void cg_post_all_to_view (view_name) char view_name[] Name of the view to post all structures If a new structure is opened after this function is called, the new structure is not automatically posted. Only the highest level structures should be posted. For example, if a structure will only be used as a reference, it should not be posted to a view. The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. POST STRUCTURE TO VIEW Add a specified structure to the list of structures to be displayed in a specified view. void cg_post_structure_to_view (view_name, structure_name) char view_name[] Name of the view to which to post char structure_name[] Name of the structure to post Only the highest level structures should be posted. For example, if a structure will only be used as a reference, it should not be posted to a view. The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. POST TO ALL VIEWS Add a specified structure to the list of structures to be displayed in all currently available views. void cg_post_to_all_views (structure_name) char structure_name[] Name of the structure to post If a new view is created after this function is called, structures are not automatically posted to the new view. Only the highest level structures should be posted. For example, if a structure will only be used as a reference, it should not be posted to a view. The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. REFERENCE STRUCTURE Add a structure reference primitive to the current structure. void cg_reference_structure (structure_name, translate, rotate, scale) char structure_name[] Name of the structure to reference t_world_coord translation New center of the referenced structure real rotation Angle of rotation in degrees real scale Scale percentage in both X and Y A structure reference draws the primitives of the specified structure, and all structure references in and below that structure, as part of the currently open structure. The current settings for primitive attributes are ignored. Attribute information is taken from the referenced primitives. The reference can be transformed from how it was originally created by specifying a translation, rotation and scale. Translation identifies a point in World Space where the origin of the referenced structure is to be placed. For example, a value of (4, 2) will translate or move the (0, 0) point of the structure to this new point. In effect, the structure is shifted to the right along the X-axis and upward along the Y-axis. Rotation rotates each primitive about the center of the X-axis and Y-axis. Scale either reduces or enlarges the visual display of the primitives. All angles assume that 0 degrees is at 3 o'clock with values increasing in the counterclockwise direction. Angles can be expressed as either positive or negative values, however, angles outside of the range 0 to 360 are normalized to that range when drawn. A structure must be open before a structure is referenced. REMOVE NAME FROM SET Remove a device class or primitive from the specified name set. void cg_remove_name_from_set (name_set, value) t_name_set *name_set Name of the set int value Device class or primitive type to remove Name sets allow the user to control which device classes are enabled or primitives are examined during a request for input. This function removes a single device class or primitive from a specified name set. This function can be called repeatedly to remove more than one class or primitive from the set. This function can be used to narrow the allowed values in a set that contains most of the primitives, except for a few. In this case, this function can be used in conjunction with the ADD ALL NAMES TO SET function to selectively remove a few of the classes or primitives. This may be preferable over having to enumerate each device class or primitive in sequence. Since name sets contain both devices classes and primitives, care should be taken to ensure proper use. REQUEST INPUT Return input from the user as either an element that was picked, a location in World space, a screen location in Normalized Device Coordinates or a string of characters from the keyboard. void cg_request_input (allowed_classes, allowed_responses, response) t_name_set allowed_devices Set of allowed input classes t_name_set allowed_responses Set of allowed primitives char *prompt Prompt to display struct t_request_buffer *response Response buffer Graphic input refers to information returned to the application program as a direct result of some action taken on the part of the user using a graphic input device such as a mouse or the keyboard. Moving the graphic cursor within tolerance of a primitive and pressing a button or key to indicate selection causes PICK information to be returned to the application indicating the type and location of the primitive. If the graphic cursor is not within tolerance of a primitive, but still inside a view, LOCATE information is returned indicating just the position of the graphic cursor. With the graphic cursor outside of a view, SCREEN information is returned. Text entered from the keyboard returns STRING information. Each of these device types are only activated if specified in the set of allowed devices. The set of allowed responses specifies the list of primitives that are examined for PICK information. With each request for input, an initial prompt can be specified that helps identify the type of request to the user. Responses from the keyboard are echoed following this prompt. After the user makes a selection, a buffer is returned that contains information about the user response. The SET STRING RESPONSE function specifies where and how the prompt characters are to be echoed on the screen. If the response is of type PICK, the response buffer identifies the highest level structure information for the pick operation. For example, if a primitive within a referenced structure was selected, the request buffer contains information about the structure reference primitive. The INQUIRE PICK LIST function provides information about the hierarchy of the pick. If the structure is not a reference, information about the actual primitive, eg. LINE or CIRCLE, is returned. Only structures that are posted to a view, visible and pickable are traversed to determine if a primitive was selected. If the response if of type LOCATE or SCREEN, the response buffer contains the location that was identified. If the response if of type STRING, the response buffer contains the characters that were entered from the keyboard. The SET STRING RESPONSE function specifies where and how the characters are to be echoed on the screen. The initial prompt should be used to identify the type of response that the user should enter, for example "Select point or enter coordinate". This example makes use of both a PICK response for the point or a STRING response for the coordinate of the point. If the user entered the coordinate from the keyboard, each character in the response would be displayed immediately after the prompt and returned in the response buffer. The application is responsible for converting the characters in the response buffer into a valid coordinate. Name sets allow the user to control which device classes are enabled or primitives are examined during a request for input. There is no difference between name sets that contain device classes and those that contain primitive values, i.e. the application does not identify the type of set in any function that deals with name sets. The application is responsible for using the appropriate name set in the correct context. SET CLASS VISIBILITY Turn the visibility of a class on or off. void cg_set_class_visibility (view_name, class, value) char view_name[] Name of the view t_class class Name of the class t_toggle value ON or OFF Visibility affects the specified class in each structure, including referenced structures. Each structure is divided into a predefined number of classes that contain primitives of a certain type. A good way to imagine this is as a table where the columns represent the structures and the rows represent the classes. Structure visibility affects an entire column and class visibility affects an entire row. In order for each individual box in this table to be visible, both the structure and class that intersect at this box must be ON. This classification of primitives provides for better viewing options. If a view becomes too cluttered, classes of primitives can be turned off much like overlays in a textbook. SET ELEMENT IDENTIFIER Initialize the current setting for the element identifier primitive attribute to the specified value. Subsequent primitives are initialized with this value. void cg_set_element_identifier (identifier) long identifier Value to assign to subsequent primitives Element identifiers are used to identify primitives for operations on structures such as deletion, edit, picking or retrieval. Primitive attributes are global over all structures and are not affected by any structure function. Deleting a primitive from a structure, for example, does not affect the attributes of any previous or subsequent primitives in the structure. SET INTERIOR STYLE Initialize the current setting for the interior style primitive attribute to the specified value. Subsequent arrow, circle, polyline and rectangle primitives are initialized with this value. void cg_interior_style (style) t_interior_style style Style to assign to subsequent primitives Primitive attributes are global over all structures and are not affected by any structure function. Deleting a primitive from a structure, for example, does not affect the attributes of any previous or subsequent primitives in the structure. SET LINE COLOR Initialize the current setting for the line color primitive attribute to the specified value. Subsequent primitives, except for text, are initialized with this value. void cg_set_line_color (color) t_color color Color to be used with subsequent primitives Enumerated values are defined for the first 16 colors. The maximum number of colors supported is device specific. Additional colors may be passed to this function without error. Undetermined results will occur if the color value is not supported. Primitive attributes are global over all structures and are not affected by any structure function. Deleting a primitive from a structure, for example, does not affect the attributes of any previous or subsequent primitives in the structure. SET LINE STYLE Initialize the current setting for the line style primitive attribute to the specified value. Subsequent primitives, except for markers and text, are initialized with this value. void cg_set_line_style (style) t_line_style style Style to use for subsequent primitives Enumerated values are defined for 6 line styles. An error will result if a value outside of this range is used. Primitive attributes are global over all structures and are not affected by any structure function. Deleting a primitive from a structure, for example, does not affect the attributes of any previous or subsequent primitives in the structure. SET LINE WIDTH Initialize the current setting for the line width primitive attribute to the specified value. Subsequent primitives, except for markers and text, are initialized with this value. void cg_set_line_width (width) int width Width of subsequent primitives The specified value refers to pixel widths which are device specific. The width of the primitive may appear differently on graphic devices that support different resolutions. Primitive attributes are global over all structures and are not affected by any structure function. Deleting a primitive from a structure, for example, does not affect the attributes of any previous or subsequent primitives in the structure. SET STRING RESPONSE Initialize the current settings used to process a response of type STRING and identify the location to display the initial prompt during a request for input. void cg_set_string_response (echo_pt, echo_color, background_color) t_ndc_coord echo_pt Location to echo each typed character t_color echo_color Color for typed characters t_color background_color Color for erasure of characters During a request for input that allows a response class of STRING, each character that is entered from the keyboard is echoed on the screen at the location and using the color that is specified. Since input does not take place in a particular view, the characters can be echoed at any location in NDC space. As the user erases characters with the backspace key, they are erased from the screen using the background color. If the echo location crosses several views which have different background colors, the characters will not appear to erase even though they will not be contained in the response from REQUEST INPUT. The echo location should be designed to be in a separate area of the screen, completely contained in a single view, or used across several views that share a common background color. The echo location is also used to display the initial prompt for each request for input. The initial prompt should be used to identify the type of response that the user should enter, for example "Select point or enter coordinate". This example makes use of both a PICK response for the point or a STRING response for the coordinate of the point. If the user entered the coordinate from the keyboard, each character in the response would be displayed immediately after the prompt and returned in the response buffer. The application is responsible for converting the characters in the response buffer into a valid coordinate. SET STRUCTURE HIGHLIGHT Mark a specified structure as to whether the primitives should be highlighted if selected during a request for input that allows primitives to be picked. void cg_set_structure_highlight (structure_name, highlight) char structure_name[] Name of the structure to change highlight t_toggle highlight Either ON or OFF Each request for input of type PICK scans the visible, pickable structures that are posted to all open views. If during the scan, a primitive is found within a fixed tolerance of the graphic cursor, the primitive is returned in the request buffer as a valid pick. It is usually desirable for the primitive to be identified to verify to the user that the correct primitive was selected. Highlighting involves erasing and redrawing the picked primitive with a slight delay in between. A special case is made for structure reference and text primitives. Since structure references may contain large amounts of primitives or further nested structures, only the individual primitive within the referenced structure is highlighted and not the structure reference primitive itself. For text, only the individual character within the test string is highlighted. The default for each structure is to highlight the picked primitive. SET STRUCTURE PICKABILITY Mark a specified structure as to whether the primitives can be picked during a request for input. void cg_set_structure_pickability (structure_name, pickable) char structure_name[] Name of the structure to change pickability t_toggle pickable Either ON or OFF Each request for input of type PICK scans the visible, pickable structures that are posted to all views. If during the scan, a primitive is found within a fixed tolerance of the graphic cursor, the primitive is returned in the request buffer as a valid pick. The default for each structure is to allow the primitives to be picked. SET STRUCTURE VISIBILITY Turn the visibility of a structure on or off. void cg_set_structure_visibility (structure_name, visible) char structure_name[] Name of the structure to change visibility t_toggle visible Either ON or OFF Each structure is divided into a predefined number of classes that contain primitives of a certain type. A good way to imagine this is as a table where the columns are all the structures and the rows are the classes. Structure visibility affects an entire column and class visibility affects an entire row. Visibility provides for better viewing options. If a view becomes too cluttered, structures or classes of primitives can be turned off much like overlays in a textbook. The default for each structure is visible. SET TEXT COLOR Initialize the current setting for the text color primitive attribute to the specified value. Subsequent text primitives are initialized with this value. void cg_set_text_color (color) t_color color Color for subsequent text primitives Enumerated values are defined for the first 16 colors. The maximum number of colors supported is device specific. Additional colors may be passed to this function without error. Undetermined results will occur if the color value is not supported. Primitive attributes are global over all structures and are not affected by any structure function. Deleting a primitive from a structure, for example, does not affect the attributes of any previous or subsequent primitives in the structure. SET WINDOW Initialize the size of the window into World space that is associated with a view. The window is then mapped to the specified view on the graphic screen. void cg_set_window (view_name, length, height) char view_name[] Name of the view to change to window real length Length of the window in World coordinates real height Height of the window in World coordinates The window defines that portion of the World space that is mapped to the view. When any view control function is applied to a view, the resultant window may not match the relative proportion of the view. Windows are always maintained with the same aspect ratio as the view to which they are applied. Windows are automatically adjusted such that more viewing range is provided than originally requested. After each view control function, the INQUIRE VIEW TRANSFORMATION function can be used to determine the exact window boundaries. For example, if the window is defined with a length of 10 units and a height of 7 units for a view whose aspect ratio is 0.5, the length will be adjusted to 14 units to match the aspect ratio. This increases the window area in World Space. The other option is to decrease the height to 5 units but, the window would not contain all of the desired area. The default window is defined with a width of 100 units and a height that varies depending on the height of the view. TERMINATE Terminate the CommonGraphics system. void cg_terminate (void) This function should be called before the application terminates. All memory areas are returned to the operating system. The graphics device is cleared and returned to the state is was in prior to the CommonGraphics session. UNPOST ALL FROM VIEW Remove all structures from the list of structures to be displayed in a specified view. void cg_unpost_all_from_view (view_name) char view_name[] Name of the view to unpost all structures The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. UNPOST FROM ALL VIEWS Remove a specified structure from the list of structures to be displayed in all views. void cg_unpost_from_all_views (structure_name) char structure_name[] Name of the structure to unpost from all views The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. UNPOST STRUCTURE FROM VIEW Remove a specified structure from the list of structures to be displayed in a specified view. void cg_unpost_structure_from_view (view_name, structure_name) char view_name[] Name of the view to unpost the structure char structure_name[] Name of the structure to unpost The contents of a structure are visible only if the structure is posted to a view or referenced by a structure that is posted to a view, the primitive is within the window of World space associated with the posted view, the visibility of the structure is ON and the visibility of the class in which primitive is added is ON. ZOOM Change the size of the window into World space that is associated with a view. void cg_zoom (view_name, window_ll, window_ur) char view_name[] Name of the view to change the window t_world_coord window_ll Lower left corner of window t_world_coord window_ur Upper right corner of window If the specified area is smaller than the current window, the visual effect will appear to zoom in, with the graphics currently in the view appearing larger. If the area is larger, the visual effect will appear to zoom out, with the graphics appearing smaller. With a zoom out, since the window has increased, it is likely that more primitives will be included in the view. When any view control function is applied to a view, the resultant window may not match the relative proportion of the view. Windows are always maintained with the same aspect ratio as the view to which they are applied. Windows are automatically adjusted such that more viewing range is provided than originally requested. After each view control function, an inquiry can be used to determine the exact window boundaries. For example, if the window is defined with a length of 10 units and a height of 7 units for a view whose aspect ratio is 0.5, the length will be adjusted to 14 units to match the aspect ratio. This increases the window area in World Space. The other option is to decrease the height to 5 units but, the window would not contain all of the desired area. Programming Techniques This example application shows the basics of using CommonGraphics. How is the graphics session initiated? How is it closed? How are structures created and posted? How are primitives and primitive attributes specified? #include <stdio.h> #include "cg.h" void main (void); t_world_coord end_pt = {24.25, 10.0}; t_world_coord start_pt = {-10.0, 10.0}; t_world_coord viewport_ll = {0.0, 0.0}; t_world_coord viewport_ur = {1.0, 1.0}; void main () { t_name_set allowed_classes; t_name_set allowed_responses; struct t_device device_params; struct t_request_buffer pick_buffer; /* Initialize the graphics session. Change the upper */ /* corner of the view to the maximum NDC range for the */ /* graphics device. */ cg_initialize (); cg_inquire_workstation (&device_params); viewport_ur[1] = device_params.aspect_ratio; /* Build the device class name set. Allow only PICK or */ /* LOCATE classes. */ allowed_classes = 0; cg_add_name_to_set (&allowed_classes, LOCATE); cg_add_name_to_set (&allowed_classes, PICK); /* Build the primitive response name set. Allow only */ /* LINEs to be picked. */ allowed_responses = 0; cg_add_name_to_set (&allowed_responses, LINE); /* Change some of the attributes. All attributes have */ /* defaults and do not have to be explicitly set by the */ /* program. Attributes also span structures which means */ /* that they do not have to be defined each time a */ /* structure is opened. */ */ cg_set_line_color (CYAN); cg_set_line_width (2); /* Open a retained structure and add a line. At this */ /* point, the line is not visible as the structure has */ /* not been posted to a view. */ cg_open_structure ("STRUCTURE1"); cg_draw_line (start_pt, end_pt); /* Open the view and adjust the window so the line */ /* appears larger. CommonGraphics changes the window to */ /* conform to the aspect ratio of the view. Setting the */ /* the view without first posting the structure */ /* eliminates the flicker caused by the view being */ /* displayed and immediately redrawn to reflect the new */ /* window. */ cg_open_view ("VIEW1", viewport_ll, viewport_ur, BLACK, BOX_BORDER); cg_set_window ("VIEW1", 400.0, 300.0); cg_post_structure_to_view ("STRUCTURE1", "VIEW1"); /* At this point the line is visible and, since it was */ /* created as a retained structure and the LINE */ /* primitive is included in the name set of allowed */ /* responses, the line may be selected. */ cg_request_input (allowed_classes, allowed_responses, "", &pick_buffer); /* Examine the element that was picked to verify that it */ /* was the line. */ if (pick_buffer.type == PICK) { if (pick_buffer.v.pick.element.type == LINE) printf ("\n A line was picked\n"); else printf ("\n Error\n"); } else printf ("\n A line was not picked\n"); /* One of the print messages is now visible. Wait for */ /* confirmation. */ cg_request_input (allowed_classes, allowed_responses, "", &pick_buffer); cg_terminate (); } Quick Reference Control initialize (void) terminate (void) dump (void) Primitive attribute set element identifier (identifier) set interior style (interior style) set line color (color) set line style (line style) set line width (width) set text color (color) Primitive draw arc (center point, start angle, end angle, rotation angle) draw arrow (tip point, length, height, rotation angle) draw bspline (number of points, point array) draw circle (center point, radius) draw ellipse (center point, x_radius, y_radius, rotation angle) draw line (start point, end point) draw marker (marker style, center point) draw polyline (marker style, connect, number of points, point array) draw rectangle (center point, length, height, corner radius, rotation angle) draw text (STRING/STROKE, lower left point, string, cell height, cell width, rotation angle) Input add all names to set (&name set, value) add name to set (&name set) remove name from set (&name set, value) request input (input class set, primitive set, prompt, &request buffer) set string response (echo location, echo color, echo background color) Structure open structure (structure name) open non retained structure (structure name) close structure (structure name) delete structure (structure name) delete all structures (void) empty structure (structure name) change structure name (old structure name, new structure name) reference structure (structure name, translation, angle, scale) set structure visibility (structure name, ON/OFF) set structure pickability (structure name, ON/OFF) set structure highlight (structure name, ON/OFF) View open view (view name, lower left viewport, upper right viewport, background color, border style) close view (view name) delete view (view name) delete all views (void) post all to view (view name) post structure to view (structure name, view name) post to all views (view name) set class visibility (view name, class, ON/OFF) unpost all from view (structure name) unpost from all views (view name) unpost structure from view (structure name, view name) View Control pan (view name, center point) set window (view name, length, height) zoom (view name, lower left point, upper right point) Edit delete element (element identifier) delete element range (element identifier, element identifier) change reference name (structure name, element identifier, old structure name, new structure name) change reference abs (structure name, reference name, element identifier, translation, angle, scale) change reference rel (structure name, reference name, element identifier, translation, angle, scale) Inquiry inquire class visibility (view name, class, &visible) inquire name set (name set, &value) inquire open structure (structure name) inquire pick list (FIRST/NEXT, pick primitive) inquire primitive attributes (¤t attribute settings) inquire string response (echo location, &echo color, &echo background color) inquire structures (FIRST/NEXT, structure name) inquire structure exists (structure name) inquire structure visibility (structure name, &visible) inquire structures posted to view (FIRST/NEXT, view name, structure name) inquire views (FIRST/NEXT, view name) inquire view attributes (view name, &color, &border style) inquire view exists (view name) inquire view transformation (view name, lower left viewport, upper right viewport, lower left window, upper right window) inquire workstation (&device attributes) Error Messages At least 2 points must be specified for a POLYLINE A POLYLINE primitive must consist of at least 3 points. Use a LINE primitive in all other cases. At least 4 points must be specified for a BSPLINE curve A BSPLINE primitive must consist of at least 4 points. Attempt to add a primitive with no open structure A structure has not been opened prior to a primitive being drawn. Cannot open CommonGraphics error file The file CG.ERR contains all error messages and the result of the DUMP function. The file was not able to be opened when an error was detected or when the DUMP function was called. Error limit for a circular arc exceeded Error limit for an ellipse exceeded An optimization is performed when drawing arcs and ellipses based on the window and view sizes. This optimization can fail if the window is exceedingly large and the corresponding viewport is very small. Adjusting either of these values should correct the error. Incorrect use of <function name> Inquiry functions that require a selection of FIRST or NEXT must be used with the FIRST selection before the NEXT selection. Invalid <parameter> specified in DRAW <primitive> The function identified in the error was not passed a correct value. Invalid response returned from device This is an internal error. The low-level device function should only return a SCREEN or STRING device class in response to a request for input. Determining whether a selection is a PICK, LOCATE or SCREEN must be performed by CommonGraphics. Marker specified in <function name> not supported The specified marker style is not supported. String truncated - The character strings used with either a structure, text primitive or view must be less than 20, 80 and 20 characters, respectively. Structure in CLOSE STRUCTURE is not open The structure is not currently open so it cannot be closed. Structure in CHANGE STRUCTURE NAME already exists The new name for the structure already exists. Structure in <function name> does not exist The structure does not exist. STRUCTURE HIGHLIGHT must be ON or OFF STRUCTURE PICKABILITY must be ON or OFF STRUCTURE VISIBILITY must be ON or OFF The value must be either ON or OFF Style used in <function name> not supported The style passed to the identified function is not supported. The values for SET WINDOW must be greater than zero The length and width of the window must be greater than zero. The corners specified in OPEN VIEW are out of range The lower left or upper right corners of the view are not valid NDC locations or the y-coordinate is outside the range of the visible screen. The maximum y-coordinate can be determined after CommonGraphics has been initialized by using the INQUIRE WORKSTATION function. The corners specified in ZOOM are the same point The window corner locations cannot be the same point. This would define a zero-length window. Unable to allocate <name> Not enough memory. In the case of not being able to allocate a structure, CommonGraphics still closes the currently open structure. This may result in a cascade of errors as subsequent primitives cannot be added to a structure. Value out of range in name set. The device class or primitive specified in ADD NAME TO SET or REMOVE NAME FROM SET is out of range. Video adapter not supported A video adapter was detected during initialization that is not supported. View in <function name> does not exist The view does not exist. Zero length line not valid in DRAW LINE The start and end points for the line cannot represent the same point.